Subject: [amos-list] Re: GUI ext, JD & Text files
From: "Rev. Giark To You" <[email-masked]>
To: Leto Kauler <[email-masked]>
Date: Sun, 18 Jul 1999 09:44:27 -0500

On 18-Jul-99, Leto Kauler wrote:
>I recently downloaded JD and GUI extensions from AMOS Factory.  I
>wanted to have a look at GUI's TCP commands but there are no docs
>included in the archive for them!  Apparently Giark has them... if
>so, could you please send them to me, mate :)

I attached the tcp docs to this message for all to get.

Well met and godspeed,
                      Rev. Giark
                                             ICQ 12235820
                                          [email-masked]
                                     [email-masked]
                                      http://24.112.23.20/~giark/
                            .----------------------------------------------.
                            |      ______  ______    _____  Coming Soon!   |
                            |     / ____/ / __  /   / ___ \ ·SoloTrek III  |
                            |    / /__   / /_/ /   / /  / /                |
                            |   / ___/  / ____ \  / /  / /  ·Cap'n Bubba   |
                            |  / /     / /___/ / / /  / /   And The Nasty  |
                            | /_/     /_______/ /_/  /_/    Alien Menace   |
                            |    Fly By Nite Videe-Oh!                     |
                            |    Amiga 1200 030/50MHz 2Mb Chip 32Mb Fast   |
                            `----------------------------------------------'
@DATABASE TCP Commands

@NODE Main "GUI Extension TCP Commands"

                                   @{b}GUI Extension@{ub}

                                   @{u}TCP Commands@{uu}
                                     @{u}25/08/98@{uu}

                                  @{" Introduction " LINK "Introduction"}
                                  @{"   Commands   " LINK "Commands"}
                                  @{" GUI Compiler " LINK "Compiler"}
@ENDNODE

@NODE "Introduction"
@NEXT "Compiler"
@PREV "Main"
@TOC "Main"
                                  !!!
                                  o o
                  +-----------oOO-(_)-OOo----------------+
                  |                                      |
                  |  Pietro Ghizzoni - Dairymen Soft     |
                  |     E-Mail:  [email-masked]        |
                  |            Team AMIGA                |
                  |                                      |
                  | Amos Professional Team Coordinator   |
                  |                                      |
                  +--------------------------------------+

Well met and godspeed,
                      Giark
                                             ICQ 12235820
                                       [email-masked]
                                http://www.hicksville.dyn.ml.org/~giark/
                            .----------------------------------------------.
                            |      ______  ______    _____                 |
                            |     / ____/ / __  /   / ___ \ Makers of      |
                            |    / /__   / /_/ /   / /  / / SoloTrek II    |
                            |   / ___/  / ____ \  / /  / /                 |
                            |  / /     / /___/ / / /  / /   CyberSpace BBS |
                            | /_/     /_______/ /_/  /_/    (519)579-0072  |
                            |    Fly By Nite Videe-Oh!      (519)579-0173  |
                            |                                              |
                            |    Amiga 1200 030/50MHz 2Mb Chip 32Mb Fast   |
                            `----------------------------------------------'

This document was created by Giark (C. Edward Stewart) after examining the
TCP example programs and email response from Pietro Ghizzoni.

These docs cover version 1.80.
@ENDNODE

@NODE "Compiler"
@NEXT "Commands"
@PREV "Introduction"
@TOC "Main"
The GUI Compiler

You don't need the GUI Compiler for your GUI Extension programs. You can use
the standard AMOSPro compiler without problems. The GUI Extension is a
standard AMOSPro v2 Extension and so it works fine with the AMOSPro compiler,
too.

If you use the GUI compiler ALL the AMOS commands work without problems. It
is when you use Gui Amiga 1, shutting off unnecessary AMOS functions, that
you may run into difficulty.

How does the GUI compiler work? What's the difference? The main difference
between the GUI and AMOSPro compilers is that the compiled code generated by
the GUI compiler hides all the AMOS "system unfriendly" code. If you zap the
code you'll see nothing AMOS related. If you zap the code generated by the
standard AMOSPro compiler, you'll find tons of AMOS stuff, like the names
of all the AMOS extensions installed in your system and other preferences.

If you trace an AMOS compiled program using SnoopDOS or other programs,
you'll notice other AMOS activities, like search for and freeze any other
running AMOS programs, search for the mysterious AMOS_Switcher and other
stuff. The GUI Compiler removes these useless operations.

If you run a virus checker together with AMOS, it will probably pop up a
warning message because some system functions have been modified.

For experts:
- Graphics.library   LoadView() only on AGA machines
- Intuition.library  EasyRequestArgs()
- Intuition.library  AutoRequest()

the GUI Compiler removes them as well.

So essentially the GUI compiler:
- hides the AMOS rubbish in the code.
- makes your AMOS programs able to run in multitasking with the other AMOS
  programs. As you know you can't run two or more AMOS programs together,
  because only the last one will run while the others will be freezed. Now
  you can!
- makes your programs more "clean" and virus checkers warnings free.

Since so many AMOS tags have been removed from the code, it is not a good
idea to use it in AMOS games, for example. The GUI Compiler is specifically
designed for {B}Workbench{UB} applications. If your program runs in the Workbench
environment, it doesn't need all the AMOS patches and hacks. For this reason,
Pietro has created the GUI Compiler.

If you need to open AMOS screens and related stuff, use the AMOSPro compiler.
If you need a nice Workbench GUI for your programs, use the GUI compiler.

About the commands that don't work anymore, this isn't a GUI Compiler effect.
It happens if you put the Gui Amiga 1 command at the start of your program.

What does Gui Amiga 1 do and why don't some commands work anymore? Simple.
The Gui Amiga 1 command disables other AMOS internal functions in order to
make your program a bit more OS friendly. In particular, this command removes
the AMOS interrupt routine. Because of this, all the VBL/interrupt-based
commands/functions don't work.

Mainly:
- Music
- Samples
- AMAL
- VBL commands and timer
- AMOS gfx

If you're creating a Workbench program, usually you don't need the above
commands, so it's a good idea to disable them.

If you do need them, don't call Gui Amiga 1 and everything will work as
usual. Therefore, Pietro suggests that you use other extensions for music and
samples, because the AMOS music extension is really badly coded.
@ENDNODE

@NODE "Commands"
@NEXT "Tcp Address"
@PREV "Compiler"
@TOC "Main"

                               @{u}The TCP Command List@{uu}

@{" =Tcp Address          " LINK "Tcp Address"}
@{" =Tcp Buffer           " LINK "Tcp Buffer"}
@{" =Tcp Channel          " LINK "Tcp Channel"}
@{" =Tcp Check            " LINK "Tcp Check"}
@{" Tcp Close             " LINK "Tcp Close"}
@{" Tcp Close A           " LINK "Tcp Close"}
@{" =Tcp Code             " LINK "Tcp Code"}
@{" =Tcp Count            " LINK "Tcp Count"}
@{" Tcp Download A to B  *" LINK "Tcp Download"}
@{" =Tcp Error            " LINK "Tcp Error"}
@{" =Tcp F Open(A,B$,C)   " LINK "Tcp F Open"}
@{" =Tcp Free(A)          " LINK "Tcp Free"}
@{" =Tcp Get(A,B,C)       " LINK "Tcp Get"}
@{" Tcp Limit A           " LINK "Tcp Limit"}
@{" =Tcp Line$(A)         " LINK "Tcp Line$"}
@{" =Tcp Open(A,B$)       " LINK "Tcp Open"}
@{" =Tcp Packet           " LINK "Tcp Packet"}
@{" =Tcp Put(A,B,C)       " LINK "Tcp Put"}
@{" =Tcp Put$(A,B$)       " LINK "Tcp Put$"}
@{" =Tcp Read(A,B,C,D)    " LINK "Tcp Read"}
@{" Tcp Remove A          " LINK "Tcp Remove"}
@{" Tcp Reset             " LINK "Tcp Reset"}
@{" =Tcp Response         " LINK "Tcp Response"}
@{" =Tcp Save(A,B,C To D)*" LINK "Tcp Save"}
@{" =Tcp Send(A,B,C,D)    " LINK "Tcp Send"}
@{" =Tcp Send$(A,B$,C)    " LINK "Tcp Send$"}
@{" Tcp Set A,B           " LINK "Tcp Set"}
@{" =Tcp Signal(A,B,C)    " LINK "Tcp Signal"}
@{" =Tcp Time             " LINK "Tcp Time"}
@{" =Tcp Total           *" LINK "Tcp Total"}
@{" Tcp Trash             " LINK "Tcp Trash"}
@{" =Tcp Type             " LINK "Tcp Type"}
@{" =Tcp User             " LINK "Tcp Remove"}

* - these commands are new and have not been fully documented yet. Use them at
    your own risk.
@ENDNODE

@NODE "Tcp Address"
@NEXT "Tcp Buffer"
@PREV "Commands"
@TOC "Main"
=Tcp Address

Returns the address of the last asynchronous TCP/IP packet sent. This is
only useful with @{"Tcp Set" LINK "Tcp Set"}.

Example:
A=Tcp Read(1,Start(10),100,0) : ADR=Tcp Address

In order to obtain the right value, you must call this command just after the
asynchronous call or at least before another asynchronous call or gui wait.
@ENDNODE

@NODE "Tcp Buffer"
@NEXT "Tcp Channel"
@PREV "Tcp Address"
@TOC "Main"
=Tcp Buffer

Returns the buffer address associated with the TCP/IP message returned by
Gui Wait.

e.g if you receive the result of a read request Tcp Buffer is the address
where the data is stored.
@ENDNODE

@NODE "Tcp Channel"
@NEXT "Tcp Check"
@PREV "Tcp Buffer"
@TOC "Main"
=Tcp Channel

Returns the channel number associated with the TCP/IP message returned by
Gui Wait
@ENDNODE

@NODE "Tcp Check"
@NEXT "Tcp Close"
@PREV "Tcp Channel"
@TOC "Main"
=Tcp Check

Check to see if there is data waiting to be read. Returns True (-1) or
False (0).
@ENDNODE

@NODE "Tcp Close"
@NEXT "Tcp Code"
@PREV "Tcp Check"
@TOC "Main"
Tcp Close

Close all open TCP connections

Tcp Close <logical file number>

Close <logical file number> TCP connection
@ENDNODE

@NODE "Tcp Code"
@NEXT "Tcp Count"
@PREV "Tcp Close"
@TOC "Main"
=Tcp Code

When you receive a TCP/IP message (Gui Wait returns -9) you can obtain the
associated code

e.g. if you receive the result of a read request, Tcp Code returns the number
of bytes received. If it's a write request, Tcp Code returns the number of
bytes transferred.
@ENDNODE

@NODE "Tcp Count"
@NEXT "Tcp Download"
@PREV "Tcp Code"
@TOC "Main"
=Tcp Count

This function returns the number of asynchronous requests sent to the
device that are waiting for responses.
@ENDNODE

@NODE "Tcp Download"
@NEXT "Tcp Error"
@PREV "Tcp Count"
@TOC "Main"
Tcp Download A To B

@ENDNODE

@NODE "Tcp Error"
@NEXT "Tcp F Open"
@PREV "Tcp Download"
@TOC "Main"
=Tcp Error

This function returns the DOS error code of the last error. When @{"Tcp Code" LINK "Tcp Code"}
equals -1 there has been a transfer error.
@ENDNODE

@NODE "Tcp F Open"
@NEXT "Tcp Free"
@PREV "Tcp Error"
@TOC "Main"
=Tcp F Open(<logical file number>,<path$>)

Open a file to write your incoming TCP data to.

e.g. X=Tcp F Open(2,"RAM:IRC.log")
@ENDNODE

@NODE "Tcp Free"
@NEXT "Tcp Get"
@PREV "Tcp F Open"
@TOC "Main"
=Tcp Free()
This will return the first free socket, starting from the specified one. This
command is useful if you have to handle a lot of TCP connections and need to
know which sockets are free for a connection.

Example:
You are currently using TCP channels 1, 2 and 3.

A=Tcp Free(1)

A will contain 4.
@ENDNODE

@NODE "Tcp Get"
@NEXT "Tcp Limit"
@PREV "Tcp Free"
@TOC "Main"
=Tcp Get(<logical file number>,<buffer>,<size>)

This function works the same way as @{"Tcp Read" LINK "Tcp Read"} only, like @{"Tcp Put" LINK "Tcp Put"}, the
command is @{I}synchronous@{UI}. The program will halt and wait for a
message to come from the TCP connection.

This command can be set to time out by using the @{"Tcp Limit" LINK "Tcp Limit"} command.

The function returns the number of bytes read.
@ENDNODE

@NODE "Tcp Limit"
@NEXT "Tcp Line$"
@PREV "Tcp Get"
@TOC "Main"
Tcp Limit <value>

Set a timeout period for @{"Tcp Get" LINK "Tcp Get"} and @{"Tcp Get$" LINK "Tcp Get$"} commands. If there is no data
available after the specified value (the value must be set as a Wait
command would be, in jiffies (50=1 Second (PAL) 60=1 Second (NTSC))), the
@{"Tcp Get" LINK "Tcp Get"} command will exit and return -1.
@ENDNODE

@NODE "Tcp Line$"
@NEXT "Tcp Open"
@PREV "Tcp Limit"
@TOC "Main"
=Tcp Line$(<logical file number>)

Reads a line of text from the specified channel. As with @{"Tcp Get" LINK "Tcp Get"}, you can
specify the timeout period using @{"Tcp Limit" LINK "Tcp Limit"}.
@ENDNODE

@NODE "Tcp Open"
@NEXT "Tcp Packet"
@PREV "Line$"
@TOC "Main"
=Tcp Open(<logical file number>,<port data$>)

Open a TCP channel using the port data

e.g. X=Tcp Open(1,"timequake.unterlab.org/6667") to open a port to IRC
@ENDNODE

@NODE "Tcp Packet"
@NEXT "Tcp Put"
@PREV "Tcp Open"
@TOC "Main"
=Tcp Packet

Returns the Packet ID of the last TCP/IP message received.

e.g.

A=Tcp Read(1,Start(10),100)
B=Tcp Send(2,Start(11),100)
C=Tcp Send(3,Start(12),100)
D=Gui Wait
IF D=-9 : Rem TCP/IP message received.
 PKT=Tcp Packet
 If PKT=A : Rem received the answer to A request
 Else If PKT=B : Rem received the answer to B request
 Else If PKT=C : Rem received the answer to C request
Endif
@ENDNODE

@NODE "Tcp Put"
@NEXT "Tcp Put$"
@PREV "Tcp Packet"
@TOC "Main"
=Tcp Put(<logical file number>,<buffer>,<size>)

This command works the same way as @{"Tcp Send" LINK "Tcp Send"}. The difference is that Tcp Put
is a @{I}synchronous@{UI} command. The program will halt until the data is
sent. This means you don't have to monitor the number of bytes sent, etc.
yourself.

The function returns the number of bytes sent.
@ENDNODE

@NODE "Tcp Put$"
@NEXT "Tcp Read"
@PREV "Tcp Put"
@TOC "Main"
=Tcp Put$(<logical file number>,<string$>)

Send a string to the TCP port

e.g. X=Tcp Put$(1,"NICK Giark")

This command works the same way as @{"Tcp Send$" LINK "Tcp Send$"}. The difference is that Tcp
Put$ is a @{I}synchronous@{UI} command. The program will halt until the data
is sent. This means you don't have to monitor the number of bytes sent, etc.
yourself.

The function returns the number of bytes sent.
@ENDNODE

@NODE "Tcp Read"
@NEXT "Tcp Remove"
@PREV "Tcp Put$"
@TOC "Main"
=Tcp Read(<logical file number>,<buffer>,<size>)

Get <size> bytes from the channel, and put them into the <buffer>, a
previously defined AMOS bank.

e.g  S=Start(10) : X=Tcp Read(1,S,100)

Using the bank as a buffer allows the command to run asynchronously. The
command doesn't wait for data to become available, it just sends a request
to the channel. When there is data to be read, Gui Wait will inform you.

A very simple example:

S=Start(10)
A=Tcp Read(1,S,100)
B=Gui Wait
If B=-9 : Rem TCP/IP message received
 D=Tcp Code : Rem D=number of bytes received
 B=Tcp Buffer : Rem B=address of the buffer where the data is stored
EndIf

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Remove"
@NEXT "Tcp Reset"
@PREV "Tcp Read"
@TOC "Main"
Tcp Remove A
Disables the @{"Tcp Signal" LINK "Tcp Signal"} mode for the specified channel.
You @{b}must@{ub} call this command when you've received a signal from the
TCP channel.
@ENDNODE

@NODE "Tcp Reset"
@NEXT "Tcp Response"
@PREV "Tcp Remove"
@TOC "Main"
Tcp Reset

Resets the TCP internal timer. After using @{"Tcp Time" LINK "Tcp Time"} you can read the amount
of time elapsed since the last Tcp Reset.
@ENDNODE

@NODE "Tcp Response"
@NEXT "Tcp Save"
@PREV "Tcp Reset"
@TOC "Main"
=Tcp Response

Some servers return ASCII responses with numeric codes on the front like:

220 Welcome to galactica.it

This command lets you get the numeric value for use in your program (Great for
IRC!). Call this command after the @{"Tcp Line$" LINK "Tcp Line$"} command.

Example:
A$=Tcp Line$ : CD=Tcp Response

Using the example above, CD would be 220.
@ENDNODE

@NODE "Tcp Save"
@NEXT "Tcp Send"
@PREV "Tcp Response"
@TOC "Main"
=Tcp Save(B,C,D To E)

@ENDNODE

@NODE "Tcp Send"
@NEXT "Tcp Send$"
@PREV "Tcp Save"
@TOC "Main"
=Tcp Send(<logical file number>,<buffer>,<code>)

Send the specified number of bytes, starting from <buffer>, to the channel.
Like @{"Tcp Read" LINK "Tcp Read"}, this command is asynchronous. The command doesn't wait for the
end of the transfer, but quits immediately so your program can continue its
work. When the transfer is complete, you will receive a TCP/IP message. See
the @{"above" LINK "Tcp Read"} example.

e.g. X=Tcp Send(1,S,125)

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Send$"
@NEXT "Tcp Set"
@PREV "Tcp Send"
@TOC "Main"
=Tcp Send$(<logical file number>,<string$>)

Send <string$> to the specified <logical file number>

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Set"
@NEXT "Tcp Signal"
@PREV "Tcp Send$"
@TOC "Main"
Tcp Set <TCP Packet Address>,<User Value>

All the asynchronous commands have a new parameter added. It is a user data.
This value will be returned to you when the TCP/IP packet comes back using the
@{"=Tcp User" LINK "Tcp User"} command. You can change the value of the user
data using Tcp Set.

Note: You can only modify this value @{b}before@{ub} calling Gui Wait. If you
try to modify a packet already returned by Gui Wait, your system will crash.
You can safely use this command to modify a Tcp Signal packet because it
remains present until you remove it.
@ENDNODE

@NODE "Tcp Signal"
@NEXT "Tcp Time"
@PREV "Tcp Set"
@TOC "Main"
=Tcp Signal(<Tcp Channel>,<Mode>,<User Data>)

Tcp Signal is a major improvement to the TCP handling system. Using this
command activates the signal mode on the specified channel. Whenthere is data
ready for download, you will be informed.

Gui Wait will still return a -9 to indicate a TCP message, but @{"Tcp Type" LINK "Tcp Type"}
will return 20 to indicate a signal. You can also use the @{"Tcp Packet" LINK "Tcp Packet"} command
and compare its value with the packet ID returned by Tcp Signal. You only need to
call Tcp Signal once.

The advantage is that, unlike @{"Tcp Read" LINK "Tcp Read"}, nothing will be downloaded or
modified. You will just be informed that there is data to be dealt with and
you can decide for yourself how best to handle it.

This command is the asynchronous version of @{"Tcp Check" LINK "Tcp Check"}.
@ENDNODE

@NODE "Tcp Time"
@NEXT "Tcp Total"
@PREV "Tcp Signal"
@TOC "Main"
=Tcp Time

Returns the amount of time elapsed since the last @{"Tcp Reset" LINK "Tcp Reset"}.
@ENDNODE

@NODE "Tcp Total"
@NEXT "Tcp Trash"
@PREV "Tcp Time"
@TOC "Main"
=Tcp Total

@ENDNODE

@NODE "Tcp Trash"
@NEXT "Tcp Type"
@PREV "Tcp Total"
@TOC "Main"
Tcp Trash

Clear @{B}all@{UB} messages from the TCP/IP port. Take care when using this command.
@ENDNODE

@NODE "Tcp Type"
@NEXT "Tcp User"
@PREV "Tcp Trash"
@TOC "Main"
=Tcp Type

Returns the type of TCP/IP message received.

87 (Asc("R")) - Received an answer to a read request
98 (Asc("W")) - Received an answer to a send request
@ENDNODE

@NODE "Tcp User"
@PREV "Tcp Type"
@TOC "Main"
=Tcp User

Returns the user data of the last TCP/IP packet received.
@ENDNODE